<!DOCTYPE html><html><head>
<title>transfer::data::destination - Data transfer facilities</title>
<style type="text/css"><!--
    HTML {
	background: 	#FFFFFF;
	color: 		black;
    }
    BODY {
	background: 	#FFFFFF;
	color:	 	black;
    }
    DIV.doctools {
	margin-left:	10%;
	margin-right:	10%;
    }
    DIV.doctools H1,DIV.doctools H2 {
	margin-left:	-5%;
    }
    H1, H2, H3, H4 {
	margin-top: 	1em;
	font-family:	sans-serif;
	font-size:	large;
	color:		#005A9C;
	background: 	transparent;
	text-align:		left;
    }
    H1.doctools_title {
	text-align: center;
    }
    UL,OL {
	margin-right: 0em;
	margin-top: 3pt;
	margin-bottom: 3pt;
    }
    UL LI {
	list-style: disc;
    }
    OL LI {
	list-style: decimal;
    }
    DT {
	padding-top: 	1ex;
    }
    UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
	font:		normal 12pt/14pt sans-serif;
	list-style:	none;
    }
    LI.doctools_section, LI.doctools_subsection {
	list-style: 	none;
	margin-left: 	0em;
	text-indent:	0em;
	padding: 	0em;
    }
    PRE {
	display: 	block;
	font-family:	monospace;
	white-space:	pre;
	margin:		0%;
	padding-top:	0.5ex;
	padding-bottom:	0.5ex;
	padding-left:	1ex;
	padding-right:	1ex;
	width:		100%;
    }
    PRE.doctools_example {
	color: 		black;
	background: 	#f5dcb3;
	border:		1px solid black;
    }
    UL.doctools_requirements LI, UL.doctools_syntax LI {
	list-style: 	none;
	margin-left: 	0em;
	text-indent:	0em;
	padding:	0em;
    }
    DIV.doctools_synopsis {
	color: 		black;
	background: 	#80ffff;
	border:		1px solid black;
	font-family:	serif;
	margin-top: 	1em;
	margin-bottom: 	1em;
    }
    UL.doctools_syntax {
	margin-top: 	1em;
	border-top:	1px solid black;
    }
    UL.doctools_requirements {
	margin-bottom: 	1em;
	border-bottom:	1px solid black;
    }
--></style>
</head>
<!-- Generated from file 'ddest.man' by tcllib/doctools with format 'html'
   -->
<!-- Copyright &amp;copy; 2006-2009 Andreas Kupries &amp;lt;andreas_kupries@users.sourceforge.net&amp;gt;
   -->
<!-- transfer::data::destination.n
   -->
<body><hr> [
   <a href="../../../../../../../../home">Tcllib Home</a>
&#124; <a href="../../../../toc.html">Main Table Of Contents</a>
&#124; <a href="../../../toc.html">Table Of Contents</a>
&#124; <a href="../../../../index.html">Keyword Index</a>
&#124; <a href="../../../../toc0.html">Categories</a>
&#124; <a href="../../../../toc1.html">Modules</a>
&#124; <a href="../../../../toc2.html">Applications</a>
 ] <hr>
<div class="doctools">
<h1 class="doctools_title">transfer::data::destination(n) 0.2 tcllib &quot;Data transfer facilities&quot;</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>transfer::data::destination - Data destination</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">Object command</a></li>
<li class="doctools_subsection"><a href="#subsection2">Object methods</a></li>
<li class="doctools_subsection"><a href="#subsection3">Options</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">snit <span class="opt">?1.0?</span></b></li>
<li>package require <b class="pkgname">transfer::data::destination <span class="opt">?0.2?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">transfer::data::destination</b> <i class="arg">objectName</i> <span class="opt">?<i class="arg">options</i>...?</span></a></li>
<li><a href="#2"><i class="arg">objectName</i> <b class="method">method</b> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></li>
<li><a href="#3"><i class="arg">objectName</i> <b class="method">destroy</b></a></li>
<li><a href="#4"><i class="arg">objectName</i> <b class="method">put</b> <i class="arg">chunk</i></a></li>
<li><a href="#5"><i class="arg">objectName</i> <b class="method">done</b></a></li>
<li><a href="#6"><i class="arg">objectName</i> <b class="method">valid</b> <i class="arg">msgvar</i></a></li>
<li><a href="#7"><i class="arg">objectName</i> <b class="method">receive</b> <i class="arg">channel</i> <i class="arg">done</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides objects mainly describing the destination of a
data transfer. They are also able to initiate the reception of
information from a channel into the described destination.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">transfer::data::destination</b> <i class="arg">objectName</i> <span class="opt">?<i class="arg">options</i>...?</span></a></dt>
<dd><p>This command creates a new data destination object with an associated
Tcl command whose name is <i class="arg">objectName</i>.
This <i class="term"><a href="../../../../index.html#object">object</a></i> command is explained in full detail in the sections
<span class="sectref"><a href="#subsection1">Object command</a></span> and <span class="sectref"><a href="#subsection2">Object methods</a></span>. The set of
supported <i class="arg">options</i> is explained in section <span class="sectref"><a href="#subsection3">Options</a></span>.</p>
<p>The object command will be created under the current namespace if the
<i class="arg">objectName</i> is not fully qualified, and in the specified
namespace otherwise.
The fully qualified name of the object command is returned as the
result of the command.</p></dd>
</dl>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">Object command</a></h3>
<p>All objects created by the <b class="cmd">::transfer::data::destination</b> command
have the following general form:</p>
<dl class="doctools_definitions">
<dt><a name="2"><i class="arg">objectName</i> <b class="method">method</b> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></dt>
<dd><p>The method <b class="method">method</b> and its <i class="arg">arg</i>'uments determine the
exact behavior of the command.
See section <span class="sectref"><a href="#subsection2">Object methods</a></span> for the detailed
specifications.</p></dd>
</dl>
</div>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">Object methods</a></h3>
<dl class="doctools_definitions">
<dt><a name="3"><i class="arg">objectName</i> <b class="method">destroy</b></a></dt>
<dd><p>This method destroys the object. Doing so while the object is busy
with the reception of information from a channel will cause errors
later on, when the reception completes and tries to access the now
missing data structures of the destroyed object.</p></dd>
<dt><a name="4"><i class="arg">objectName</i> <b class="method">put</b> <i class="arg">chunk</i></a></dt>
<dd><p>The main receptor method. Saves the received <i class="arg">chunk</i> of data into
the configured destination. It has to be called for each piece of data
received.</p></dd>
<dt><a name="5"><i class="arg">objectName</i> <b class="method">done</b></a></dt>
<dd><p>The secondary receptor method. Finalizes the receiver. It has to be
called when the receiving channel signals EOF. Afterward neither
itself nor method <b class="method">put</b> can be called anymore.</p></dd>
<dt><a name="6"><i class="arg">objectName</i> <b class="method">valid</b> <i class="arg">msgvar</i></a></dt>
<dd><p>This method checks the configuration of the object for validity. It
returns a boolean flag as result, whose value is <b class="const">True</b> if the
object is valid, and <b class="const">False</b> otherwise. In the latter case the
variable whose name is stored in <i class="arg">msgvar</i> is set to an error
message describing the problem found with the configuration. Otherwise
this variable is not touched.</p></dd>
<dt><a name="7"><i class="arg">objectName</i> <b class="method">receive</b> <i class="arg">channel</i> <i class="arg">done</i></a></dt>
<dd><p>This method initiates the reception of data from the specified
<i class="arg">channel</i>. The received data will be stored into the configured
destination, via calls to the methods <b class="method">put</b> and <b class="method">done</b>.
When the reception completes the command prefix <i class="arg">done</i> is invoked,
with the number of received characters appended to it as the sole
additional argument.</p></dd>
</dl>
</div>
<div id="subsection3" class="doctools_subsection"><h3><a name="subsection3">Options</a></h3>
<p>All data destinations support the options listed below. It should be
noted that all are semi-exclusive, each specifying a different type of
destination and associated information. If these options are specified
more than once then the last option specified is used to actually
configure the object.</p>
<dl class="doctools_options">
<dt><b class="option">-channel</b> <i class="arg">handle</i></dt>
<dd><p>This option specifies that the destination of the data is a channel,
and its associated argument is the handle of the channel to write the
received data to.</p></dd>
<dt><b class="option">-file</b> <i class="arg">path</i></dt>
<dd><p>This option specifies that the destination of the data is a file, and
its associated argument is the path of the file to write the received
data to.</p></dd>
<dt><b class="option">-variable</b> <i class="arg">varname</i></dt>
<dd><p>This option specifies that the destination of the data is a variable,
and its associated argument contains the name of the variable to write
the received data to. The variable is assumed to be global or
namespaced, anchored at the global namespace.</p></dd>
<dt><b class="option">-progress</b> <i class="arg">command</i></dt>
<dd><p>This option, if specified, defines a command to be invoked for each
chunk of bytes received, allowing the user to monitor the progress of
the reception of the data. The callback is always invoked with one
additional argument, the number of bytes received so far.</p></dd>
</dl>
</div>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>transfer</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#channel">channel</a>, <a href="../../../../index.html#copy">copy</a>, <a href="../../../../index.html#data_destination">data destination</a>, <a href="../../../../index.html#transfer">transfer</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Transfer module</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright &copy; 2006-2009 Andreas Kupries &lt;andreas_kupries@users.sourceforge.net&gt;</p>
</div>
</div></body></html>
